OpenEdge Development: <br />Web Services Binding to a server object handle

As for an AppServer, you use the CONNECT( ) method on the server object handle to bind that server object handle to a Web service. This is the basic syntax:

Syntax
CONNECT ( `connection-parameters` [ , `userid` ] [ , `password` ] [ , `app-server-info` ] )

A Web service binding requires and uses only the connection-parameters argument, which is a character string containing embedded parameter values to specify the binding. For a Web service, the last three parameters are AppServer-specific parameters and are ignored if specified.

The connection-parameters parameter string can contain connection parameters for either an AppServer application service, a Web service, or both. If the string contains any Web service parameters, OpenEdge assumes that the method is binding to a Web service and ignores any AppServer-specific connection parameters in the string.

Connection parameters

The primary function of the connection parameters is to specify the location and transport information for the Web service on the network. Web services provide two separate mechanisms for doing this. OpenEdge supports both mechanisms through the Web service connection parameters.

Syntax
-WSDL `wsdl-document` [ -WSDLUserid `user-id` [ -WSDLPassword `password` ] ] { { [ -Service `service-name` [ -ServiceNamespace `service-namespace` ] ] [ -Port `port-name` ] } \| { [ [ -Binding `binding-name` [ -BindingNamespace `binding-namespace` ] ] -SOAPEndpoint `URL-endpoint` ] } } [ -SOAPEndpointUserid `user-id` [ -SOAPEndpointPassword `password` ] ] [ -TargetNamespace `targetNamespace` ] [ -maxConnections `num-connections` ] [ -connectionLifetime `nSeconds` ] [ -nohostverify ] [ -nosessionreuse ] [ -pf `filename` ]

-WSDL wsdl-document [ -WSDLUserid user-id [ -WSDLPassword password ] ] 
{ 
     { 
        [ -Service service-name [ -ServiceNamespace service-namespace ] ] 
        [ -Port port-name ] 
     } 
  | 
     { 
        [ [ -Binding binding-name [ -BindingNamespace binding-namespace ] ] 
            -SOAPEndpoint URL-endpoint ] 
     } 
} 
[ -SOAPEndpointUserid user-id [ -SOAPEndpointPassword password ] ] 
[ -TargetNamespace targetNamespace ] 
[ -maxConnections num-connections ] 
[ -connectionLifetime nSeconds ] 
[ -nohostverify ] 
[ -nosessionreuse ] 
[ -pf filename ]

The only fully required element is the -WSDL parameter to identify the WSDL document for the Web service. Note that the remaining “required” elements specify service, port, and binding information, but contain only optional elements. This is to indicate that if the WSDL document contains enough unambiguous information to specify both a valid transport and location for the Web service, you do not have to specify any of this information in the connection parameters, and the Web service will be bound according to the WSDL. This is only possible for a WSDL with a single service and port specification, because there is no provision for specifying a SOAP endpoint in WSDL without defining a service.

Also, if the WSDL unambiguously specifies only some of the required information, the connection parameters need only contain the required options to unambiguously complete the transport and location information in the WSDL document. So, for a service and port specification, you can specify either a -Service option (to unambiguously identify one or more services that define a single port in the WSDL) or a -Port option (to specify one of several ports defined for a single service in the WSDL). For a binding and SOAP endpoint specification, the minimum required element is the -SOAPEndpoint connection parameter, which can complete the location specification for a WSDL that defines a single <binding> element. If the WSDL contains multiple services, ports, or bindings, the connection parameters must specify the necessary -Service/-Port or -Binding/-SOAPEndpoint options to uniquely and correctly identify the transport and location.

If the WSDL defines a single service, port, and binding, and you include no service, port, and binding options in the connection parameters, the WSDL-defined service and port take precedence. If your connection parameters include both valid -Service/-Port and valid -Binding/-SOAPEndpoint options, the CONNECT( ) method fails.

In all cases, any specified service, port, or binding options must match the corresponding WSDL entries exactly with respect to namespace, local name, and letter case; otherwise, the CONNECT( ) method fails. If the WSDL defines multiple services, ports, or bindings, and the connection parameters do not specify the necessary service, port, or binding options, the CONNECT( ) method also fails.

Table 9–1 provides a short description for each parameter in the Web service connection parameter string, in the order they appear in the syntax. For more information on these parameters, see the CONNECT( ) method entry in OpenEdge Development: Progress 4GL Reference .

Table 9–1: Web service connection parameters
Connection parameter	Description
-WSDL `wsdl-document`	URL, UNC, or local file pathname (possibly relative) to the WSDL file that describes the Web service.
-WSDLUserid `user-id`	Username to authenticate access to the WSDL file (overridden by any username specified in the WSDL URL).
-WSDLPassword `password`	Password to authenticate access to the WSDL file (overridden by any password specified in the WSDL URL).
-Service `service-name`	Name of a `<service>` element in the WSDL.
-ServiceNamespace `service-namespace`	Namespace to disambiguate duplicate-named `<service>` elements.
-Port `port-name`	Name of a `<port>` element defined in the specified `<service>` element.
-Binding `binding-name`	Name of a `<binding>` element in the WSDL.
-BindingNamespace `binding-namespace`	Namespace to disambiguate duplicate-named `<binding>` elements.
-SOAPEndpoint `URL-endpoint`	URL location for the Web service.
-SOAPEndpointUserid `user-id`	Username to authenticate access (by either `-Service` or `-Binding`) to the Web service.
-SOAPEndpointPassword `password`	Password to authenticate access (by either `-Service` or `-Binding`) to the Web service.
-TargetNamespace `targetNamespace`	The target namespace specified in the WSDL for the Web service must match, as a verification check.
-maxConnections `num-connections`	Maximum number of simultaneous (parallel) connections maintained between the client and Web service for asynchronous requests.
-connectionLifetime `nSeconds`	The maximum number of seconds that a given connection can be reused for asynchronous requests before it is destroyed.
`-no`hostverify	If specified, turns off host verification for a Secure Socket Layer (SSL) connection using HTTPS. Without this parameter specified, the client compares the host name specified in the URL with the Common Name specified in the server certificate, and raises an error if they do not match. With this parameter specified, the client never raises the error. For more information, see the sections on managing the OpenEdge certificate store in OpenEdge Getting Started: Core Business Services .¹
-nosessionreuse	If specified, the connection does not reuse the SSL session ID when reconnecting to the same Web server using HTTPS.¹
-pf `filename`	File containing any parameters specified in the `CONNECT( )` method.

¹These connection parameters affect all SSL connections made using the Web service server handle, including any WSDL file access or Web service access that uses HTTPS.

Using HTTPS

When you use HTTPS to make a secure connection to a Web service, you might have to manage the OpenEdge certificate store to contain the necessary digital certificates for SSL verification. For information on managing the OpenEdge certificate store, see OpenEdge Getting Started: Core Business Services .

Invoking the binding

These examples show use of the two mechanisms for binding an actual Web service:

Binding results

After a successful attempt to bind a Web service, the server object is initialized for the Web service. This means that on the server object handle the: